---
title: Lua Reference - kong.tools.utils
layout: default
---


<header class="page-header">
  <div class="container">
    <div class="page-header-icon">
      <img src="/assets/images/icons/icn-documentation.svg" alt="Documentation" />
    </div>
    <div class="page-header-title">
      <h1>Public Lua API Reference</h1>
      <p>For plugins developers and core contributors</p>
    </div>
    {% if site.data.kong_versions.size > 1 %}
      {% include lua-reference-dropdown.html
        page=page
        site=site
      %}
    {% endif %}
  </div>
</header>

<div class="container">
  <aside class="page-navigation">
    <nav>
      <ul>
        <li>
          <a href="/{{page.kong_version}}"><h5>Back to docs</h5></a>
        </li>
        <li>
          <a href="/{{page.kong_version}}/lua-reference/"><h5>Index</h5></a>
        </li>
        <li>
          <h5>Modules</h5>
          <ul>
            <li><a href="../../modules/kong.dao.cassandra.base_dao">kong.dao.cassandra.base_dao</a></li>
            <li><a href="../../modules/kong.plugins.basic-auth.crypto">kong.plugins.basic-auth.crypto</a></li>
            <li><a href="../../modules/kong.plugins.jwt.jwt_parser">kong.plugins.jwt.jwt_parser</a></li>
            <li><a href="../../modules/kong.plugins.log-serializers.alf">kong.plugins.log-serializers.alf</a></li>
            <li><a href="../../modules/kong.tools.io">kong.tools.io</a></li>
            <li><a href="../../modules/kong.tools.responses">kong.tools.responses</a></li>
            <li><a href="../../modules/kong.tools.timestamp">kong.tools.timestamp</a></li>
            <li>kong.tools.utils</li>
          </ul>
        </li>
      </ul>
    </nav>
  </aside>

  <div class="page-content-container">
  <div class="page-content">
    <div class="content">
<h1><code>kong.tools.utils</code></h1>
<p>Module containing some general utility functions</p>
<p></p>



<h2><a href="#Functions">Functions</a></h2>
<table class="function_list">
  <tr>
    <td class="name"><a href="#add_error">add_error (errors, k, v)</a></td>
    <td class="summary">Add an error message to a key/value table.</td>
  </tr>
  <tr>
    <td class="name"><a href="#deep_copy">deep_copy (orig)</a></td>
    <td class="summary">Deep copies a table into a new table.</td>
  </tr>
  <tr>
    <td class="name"><a href="#is_array">is_array (t)</a></td>
    <td class="summary">Checks if a table is an array and not an associative array.</td>
  </tr>
  <tr>
    <td class="name"><a href="#load_module_if_exists">load_module_if_exists (module_name)</a></td>
    <td class="summary">Try to load a module.</td>
  </tr>
  <tr>
    <td class="name"><a href="#random_string">random_string ()</a></td>
    <td class="summary">Generates a random unique string</td>
  </tr>
  <tr>
    <td class="name"><a href="#table_contains">table_contains (arr, val)</a></td>
    <td class="summary">Checks if a value exists in a table.</td>
  </tr>
  <tr>
    <td class="name"><a href="#table_merge">table_merge (t1, t2)</a></td>
    <td class="summary">Merges two table together.</td>
  </tr>
  <tr>
    <td class="name"><a href="#table_size">table_size (t)</a></td>
    <td class="summary">Calculates a table size.</td>
  </tr>
</table>


<h2 class="section-header "><a name="Functions">Functions</a></h2>


<dl class="function">
  <hr />
  <dt>
    <h4><a name="add_error">add_error</a></h4>
  </dt>
  <dd>
    Add an error message to a key/value table.
 If the key already exists, a sub table is created with the original and the new value.

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">errors</code>
          (Optional) Table to attach the error to. If <code>nil</code>, the table will be created.
        </li>
        <li>
          <code class="parameter">k</code>
          Key on which to insert the error in the <code>errors</code> table.
        </li>
        <li>
          <code class="parameter">v</code>
          Value of the error
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        The <code>errors</code> table with the new error inserted.
      </li>
    </ul>





  </dd>
  <hr />
  <dt>
    <h4><a name="deep_copy">deep_copy</a></h4>
  </dt>
  <dd>
    Deep copies a table into a new table.
 Tables used as keys are also deep copied, as are metatables

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">orig</code>
          The table to copy
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        Returns a copy of the input table
      </li>
    </ul>





  </dd>
  <hr />
  <dt>
    <h4><a name="is_array">is_array</a></h4>
  </dt>
  <dd>
    Checks if a table is an array and not an associative array.
 <strong>* NOTE *</strong> string-keys containing integers are considered valid array entries!

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">t</code>
          The table to check
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        Returns <code>true</code> if the table is an array, <code>false</code> otherwise
      </li>
    </ul>





  </dd>
  <hr />
  <dt>
    <h4><a name="load_module_if_exists">load_module_if_exists</a></h4>
  </dt>
  <dd>
    Try to load a module.
 Will not throw an error if the module was not found, but will throw an error if the
 loading failed for another reason (eg: syntax error).

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">module_name</code>
          Path of the module to load (ex: kong.plugins.keyauth.api).
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        success A boolean indicating whether the module was found.
      </li>
      <li>
        module The retrieved module.
      </li>
    </ul>





  </dd>
  <hr />
  <dt>
    <h4><a name="random_string">random_string</a></h4>
  </dt>
  <dd>
    Generates a random unique string


    <h5>Returns:</h5>
    <ul>
      <li>
        string  The random string (a uuid without hyphens)
      </li>
    </ul>





  </dd>
  <hr />
  <dt>
    <h4><a name="table_contains">table_contains</a></h4>
  </dt>
  <dd>
    Checks if a value exists in a table.

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">arr</code>
          The table to use
        </li>
        <li>
          <code class="parameter">val</code>
          The value to check
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        Returns <code>true</code> if the table contains the value, <code>false</code> otherwise
      </li>
    </ul>





  </dd>
  <hr />
  <dt>
    <h4><a name="table_merge">table_merge</a></h4>
  </dt>
  <dd>
    Merges two table together.
 A new table is created with a non-recursive copy of the provided tables

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">t1</code>
          The first table
        </li>
        <li>
          <code class="parameter">t2</code>
          The second table
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        The (new) merged table
      </li>
    </ul>





  </dd>
  <hr />
  <dt>
    <h4><a name="table_size">table_size</a></h4>
  </dt>
  <dd>
    Calculates a table size.
 All entries both in array and hash part.

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">t</code>
          The table to use
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        number The size
      </li>
    </ul>





  </dd>
</dl>


    </div>
  </div>
</div>
</div>
